Overview of Quarto

In brief, quarto is a powerful open-source tool for creating dynamic documents, reports, presentations, and websites using a simple markdown-based format. It is designed to facilitate reproducible research and data science workflows by allowing users to combine code, text, and visualizations in a single document. Some key features of quarto include:

  • Multi-language support: Quarto supports multiple programming languages, including R, Python, Julia, and JavaScript. This allows users to create documents that combine code from different languages seamlessly.
  • Reproducibility: Quarto enables users to create reproducible documents by embedding code chunks that can be executed to generate results and visualizations. This ensures that the document can be easily updated when the underlying data or analysis changes.

Anatomy of a Quarto (.qmd) Document

A quarto (.qmd) document typically consists of the following components:

  1. YAML Front Matter: the document header
  2. Code Chunks: code sections that can be executed within the document
  3. Markdown Content: the main body (text) of the document

1. YAML Front Matter

The YAML front matter is a section at the top of the document that contains metadata about the document, such as the title, author, date, and output format. It is enclosed within triple dashes (---).

Example YAML front matter:

---
title: "My Quarto Document"
author: "Your Name"
date: "Insert Date"
format: html
---

Note: In order to preview or render a quarto document with R code, you need to have rmarkdown installed in your active R environment (via install.packages("rmarkdown")).

Example YAML front matter:

---
title: "My Quarto Document"
author: "Your Name"
date: "Insert Date"
format: html
jupyter: python3
---

Note: In order to preview or render a quarto document with jupyter: python3, you need to have Jupyter/JupyterLab installed in your active Python environment. For example, if you are using conda, you should run conda install jupyter before rendering the document.

In this example, the YAML front matter specifies the title, author, date, and output format (HTML) of the document. You can change the output format to PDF, Word, and many other supported formats. For more details, see the Quarto Reference page.

If you want to run both R and Python code chunks in the same document, do not include the jupyter: python3 line in the YAML front matter. Instead, you will need to install reticulate in R via: install.packages("reticulate").

Some additional options you might find useful in the YAML front matter include:

---
title: "My Quarto Document"
author: "Your Name"
date: "Insert Date"
format:
  html:
    theme: sandstone # html theme
    toc: true # show table of contents
    lightbox: true # can click on images to enlarge
    code-fold: true # fold code chunks by default
    code-summary: "Show Code" # text for code fold button
execute:
  echo: true # show code output by default
  warning: false # suppress warnings output by default
  message: false # suppress messages output by default
---

These options and more can help customize the appearance of your quarto document (learn more here).

2. Code Chunks

Code chunks are sections of code that can be executed within the document. Code chunks are enclosed within triple backticks (```) and can specify the programming language used.

Example R code chunk:

Show Code
x <- c(1, 2, 3)
y <- c(4, 5, 6)
plot(x, y)
Figure 1: An example plot in R

Example Python code chunk:

Show Code
import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [4, 5, 6])
plt.show()
Figure 2: An example plot in Python

In these code chunks, we included chunk options (preceded by #|) to customize the output, such as figure labels, captions, and dimensions. For more details on chunk options, see these reference pages for Python and R.

Note that if you set jupyter: python3 in the YAML front matter, the fig-width and fig-height options are not supported; in order to change the figure size, you will need to do so within the code chunk itself (e.g., using plt.figure(figsize=(6,4)) in Python).

3. Markdown Content

Markdown content typically makes up the bulk of a quarto document. This is where you write the text, explanations, and narratives that accompany your code and results. Broadly speaking, Markdown is a lightweight markup language that allows you to format text using simple syntax.

Markdown Syntax Output
*italics*, **bold**, ***bold italics***
italics, bold, bold italics
superscript^2^ / subscript~2~
superscript2 / subscript2
`verbatim code`
verbatim code
<https://quarto.org/>
https://quarto.org/
[Quarto](https://quarto.org)
Quarto
Markdown Syntax Output
# Heading 1

Heading 1

## Heading 2

Heading 2

### Heading 3

Heading 3

#### Heading 4

Heading 4

Markdown Syntax Output
- unordered list
  - sub-item 1
  - sub-item 2
    - sub-sub-item 1
  • unordered list
    • sub-item 1
    • sub-item 2
      • sub-sub-item 1
1. ordered list
2. item 2
   i) sub-item 1
      A.  sub-sub-item 1
  1. ordered list
  2. item 2
    1. sub-item 1
      1. sub-sub-item 1

Use $ delimiters for inline math and $$ delimiters for display math. For example:

Markdown Syntax Output
inline math: $E = mc^{2}$
inline math: \(E=mc^{2}\)
display math:

$$E = mc^{2}$$

display math:

\[E = mc^{2}\]

Markdown Syntax
:::{.callout-note}
Note that there are five types of callouts, including: 
`note`, `tip`, `warning`, `caution`, and `important`.
:::
Output
Note

Note that there are five types of callouts, including note, tip, warning, caution, and important.

Learn more in the article on Callout Blocks.

You can create cross-references to figures, tables, sections, and equations using labels.

Markdown Syntax Output
@fig-r
Figure 1
### Example Section {#sec-ex}
@sec-ex

Example Section

Section 1.1.2

Notes:

  • To reference a figure generated from a code chunk, you must include a label in the corresponding code chunk (e.g., #| label: fig-r in the R code chunk example above).
  • To reference a section, you must include a label in the section heading (e.g., {#sec-ex} in the section heading example above) and set number-sections: true in the YAML front matter so that the section numbers are generated.

More information on cross-references can be found here.

To see more examples of common markdown elements used in quarto documents, check out these resources:

Some additional quarto-specific features for enhancing your documents include:

Rendering Quarto Documents

Before rendering quarto documents, you must have the following packages installed in your active R/Python environment:

  • When using R only: rmarkdown
    • Install via install.packages("rmarkdown") in your R console
  • When using Python only (with jupyter: python3 in YAML front matter): jupyter
    • Install via conda install jupyter in your terminal
  • When using R and Python together: rmarkdown and reticulate
    • Install via install.packages("rmarkdown") and install.packages("reticulate") in your R console

Now to render a quarto document into the desired output format (e.g., HTML, PDF, Word), you can use one of the following methods:

  1. Command Line:

    Open your terminal, navigate to the directory containing your .qmd file, and run the following command:

    quarto render {your_document}.qmd
  2. RStudio/Positron:

    If you are using Positron (or RStudio or VS Code), you can click the “Preview” or “Render” button at the top of the editor window when you have your .qmd file open.

Additional Resources

For more information on using quarto, check out the following resources: